'\" te
.\" Copyright (c) 2007, Sun Microsystems, Inc., All Rights Reserved
.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License").  You may not use this file except in compliance with the License.
.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.  See the License for the specific language governing permissions and limitations under the License.
.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE.  If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
.TH KICONV_OPEN 9F "Nov 5, 2013"
.SH NAME
kiconv_open \- code conversion descriptor allocation function
.SH SYNOPSIS
.nf
#include <sys/sunddi.h>



\fBkiconv_t\fR \fBkiconv_open\fR(\fBconst\fR \fBchar *\fR\fItocode\fR, \fBconst\fR \fBchar *\fR\fIfromcode\fR);
.fi

.SH INTERFACE LEVEL
illumos DDI specific (illumos DDI).
.SH PARAMETERS
.ne 2
.na
\fB\fItocode\fR\fR
.ad
.RS 12n
Points to a target codeset name string.
.RE

.sp
.ne 2
.na
\fB\fIfromcode\fR\fR
.ad
.RS 12n
Points to a source codeset name string.
.RE

.SH DESCRIPTION
The \fBkiconv_open()\fR function returns a code conversion descriptor that
describes a conversion from the codeset specified by \fIfromcode\fR to the
codeset specified by \fItocode\fR. For state-dependent encodings, the
conversion descriptor is in a codeset-dependent initial state (ready for
immediate use with the \fBkiconv()\fR function).
.sp
.LP
Supported code conversions are between \fBUTF-8\fR and the following:
.sp
.in +2
.nf
Name                    Description

 Big5                    Traditional Chinese Big5
 Big5-HKSCS              Traditional Chinese Big5-Hong Kong
                         Supplementary Character Set
 CP720                   DOS Arabic
 CP737                   DOS Greek
 CP850                   DOS Latin-1 (Western European)
 CP852                   DOS Latin-2 (Eastern European)
 CP857                   DOS Latin-5 (Turkish)
 CP862                   DOS Hebrew
 CP866                   DOS Cyrillic Russian
 CP932                   Japanese Shift JIS (Windows)
 CP950-HKSCS             Traditional Chinese HKSCS-2001 (Windows)
 CP1250                  Central Europe
 CP1251                  Cyrillic
 CP1252                  Western Europe
 CP1253                  Greek
 CP1254                  Turkish
 CP1255                  Hebrew
 CP1256                  Arabic
 CP1257                  Baltic
 EUC-CN                  Simplified Chinese EUC
 EUC-JP                  Japanese EUC
 EUC-JP-MS               Japanese EUC MS
 EUC-KR                  Korean EUC
 EUC-TW                  Traditional Chinese EUC
 GB18030                 Simplified Chinese GB18030
 GBK                     Simplified Chinese GBK
 ISO-8859-1              Latin-1 (Western European)
 ISO-8859-2              Latin-2 (Eastern European)
 ISO-8859-3              Latin-3 (Southern European)
 ISO-8859-4              Latin-4 (Northern European)
 ISO-8859-5              Cyrillic
 ISO-8859-6              Arabic
 ISO-8859-7              Greek
 ISO-8859-8              Hebrew
 ISO-8859-9              Latin-5 (Turkish)
 ISO-8859-10             Latin-6 (Nordic)
 ISO-8859-13             Latin-7 (Baltic)
 ISO-8859-15             Latin-9 (Western European with euro sign)
 KOI8-R                  Cyrillic
 Shift_JIS               Japanese Shift JIS (JIS)
 TIS_620                 Thai (a.k.a. ISO 8859-11)
 Unified-Hangul          Korean Unified Hangul

.fi
.in -2
.sp

.sp
.LP
\fBUTF-8\fR and the above names can be used at \fItocode\fR and \fIfromcode\fR
to specify the desired code conversion. The following aliases are also
supported as alternative names to be used:
.sp
.in +2
.nf
Aliases                 Original Name
  720                     CP720
  737                     CP737
  850                     CP850
  852                     CP852
  857                     CP857
  862                     CP862
  866                     CP866
  932                     CP932
  936, CP936              GBK
  949, CP949              Unified-Hangul
  950, CP950              Big5
  1250                    CP1250
  1251                    CP1251
  1252                    CP1252
  1253                    CP1253
  1254                    CP1254
  1255                    CP1255
  1256                    CP1256
  1257                    CP1257
  ISO-8859-11             TIS_620
  PCK, SJIS               Shift_JIS
.fi
.in -2
.sp

.sp
.LP
A conversion descriptor remains valid until it is closed by using
\fBkiconv_close()\fR.
.SH RETURN VALUES
Upon successful completion, \fBkiconv_open()\fR returns a code conversion
descriptor for use on subsequent calls to \fBkiconv()\fR. Otherwise, if the
conversion specified by \fIfromcode\fR and \fItocode\fR is not supported or for
any other reasons the code conversion descriptor cannot be allocated,
\fBkiconv_open()\fR returns (\fBkiconv_t\fR)-1 to indicate the error.
.SH CONTEXT
\fBkiconv_open()\fR can be called from user context only.
.SH EXAMPLES
\fBExample 1 \fROpening a Code Conversion
.sp
.LP
The following example shows how to open a code conversion from \fBISO\fR
8859-15 to \fBUTF-8\fR

.sp
.in +2
.nf
#include <sys/sunddi.h>

kiconv_t cd;

cd = kiconv_open("UTF-8", "ISO-8859-15");
if (cd == (kiconv_t)-1) {
         /* Cannot open up the code conversion. */
         return (-1);
}
.fi
.in -2

.SH ATTRIBUTES
See \fBattributes\fR(7) for descriptions of the following attributes:
.sp

.sp
.TS
box;
c | c
l | l .
ATTRIBUTE TYPE	ATTRIBUTE VALUE
_
Interface Stability	Committed
.TE

.SH SEE ALSO
.BR iconv (3C),
.BR iconv_close (3C),
.BR iconv_open (3C),
.BR u8_strcmp (3C),
.BR u8_textprep_str (3C),
.BR u8_validate (3C),
.BR uconv_u16tou32 (3C),
.BR uconv_u16tou8 (3C),
.BR uconv_u32tou16 (3C),
.BR uconv_u32tou8 (3C),
.BR uconv_u8tou16 (3C),
.BR uconv_u8tou32 (3C),
.BR attributes (7),
.BR kiconv (9F),
.BR kiconv_close (9F),
.BR kiconvstr (9F),
.BR u8_strcmp (9F),
.BR u8_textprep_str (9F),
.BR u8_validate (9F),
.BR uconv_u16tou32 (9F),
.BR uconv_u16tou8 (9F),
.BR uconv_u32tou16 (9F),
.BR uconv_u32tou8 (9F),
.BR uconv_u8tou16 (9F),
.BR uconv_u8tou32 (9F)
.sp
.LP
The Unicode Standard
.sp
.LP
http://www.unicode.org/standard/standard.html
.SH NOTES
The code conversions are available between \fBUTF-8\fR and the above noted
\fIcodesets\fR. For example, to convert from \fBEUC-JP \fRto \fBShift_JIS\fR,
first convert \fBEUC-JP\fR to \fBUTF-8\fR and then convert \fBUTF-8\fR to
\fBShift_JIS\fR.
.sp
.LP
The code conversions supported are based on simple one-to-one mappings. There
is no special treatment or processing done during code conversions such as case
conversion, Unicode Normalization, or mapping between combining or conjoining
sequences of \fBUTF-\fR8 and pre-composed characters in non-\fBUTF-8\fR
codesets.
.sp
.LP
All supported non-\fBUTF-8\fR codesets use pre-composed characters only.
However, \fBUTF-8\fR allows combining or conjoining characters too. For this
reason, using a form of Unicode Normalizations on \fBUTF-8\fR text with
\fBu8_textprep_str()\fR before or after doing code conversions might be
necessary.
